Skip to content

docs: publish Sourcey-generated llms.txt - #37

Open
codexbounty260804 wants to merge 1 commit into
gridaco:mainfrom
codexbounty260804:add-sourcey-llms
Open

docs: publish Sourcey-generated llms.txt#37
codexbounty260804 wants to merge 1 commit into
gridaco:mainfrom
codexbounty260804:add-sourcey-llms

Conversation

@codexbounty260804

@codexbounty260804 codexbounty260804 commented Aug 4, 2026

Copy link
Copy Markdown

Summary

  • Generate a canonical repository-root llms.txt from 21 authoritative Markdown pages with Sourcey 3.6.5.
  • Make every website build verify that the tracked file is current and copy that exact file to www/public/llms.txt.
  • Pin the generator in the website lockfile, document regeneration, and declare text/plain; charset=utf-8 for the published route.

Closes #23.

Change classification

  • Language-contract-preserving implementation, tooling, documentation, tests, or refactor
  • Isolated, opt-in, non-normative pre-1.0 experiment or prototype
  • Committee-sponsored RFD draft, review revision, or decision record
  • Implementation or specification synchronization authorized by an accepted RFD
  • Non-normative working-group study or meeting record
  • Governance or contribution-process change

Language-change gate

  • Related issue: chore: add llms.txt for the repository and spock.sh #23
  • Language-problem issue: Not applicable; this does not change the language.
  • Committee sponsor/shepherd: Not applicable.
  • Accepted RFD: Not applicable.
  • Implementation tracking issue: Not applicable.
  • Language-contract preservation: This adds a generated discovery index and build-time copy/check only. It does not change syntax, semantics, the runtime, or normative specification content.
  • Experiment boundary: Not applicable.
  • Governance public-review dates: Not applicable.
  • Governance decision record: Not applicable.

Before and after

Before: Spock had no canonical LLM discovery index, and https://spock.sh/llms.txt returned 404.

After: The repository tracks one Sourcey-generated llms.txt. The normal Astro build fails when it is stale, copies that exact canonical file into the static output, and Vercel serves it as plain text.

Scope and tradeoffs

The index stays compact and links to authoritative pages rather than duplicating the documentation corpus. Sourcey 3.6.5 is an exact development dependency, so regeneration is deterministic and covered by the existing lockfile. llms-full.txt is intentionally out of scope.

Verification

  • node scripts/generate-llms.mjs — generated 21 Sourcey pages.

  • node scripts/generate-llms.mjs --check --publish — idempotent; canonical and published bytes matched exactly.

  • Canonical SHA-256: a69e37836161c55711eb0f67e343d787c0fe7a2140558e947d41ece11ec3d48c.

  • Audited all 27 unique destinations in the index: 27/27 returned HTTP 2xx/3xx.

  • astro check — 0 errors, 0 warnings, 0 hints.

  • astro build — 35 pages built; dist/llms.txt matched the canonical file byte for byte.

  • corepack pnpm@10.11.0 -C www install --frozen-lockfile — lockfile current.

  • git diff --check — clean.

  • I read and followed CONTRIBUTING.md.

  • I added or updated focused tests, or explained why no test applies.

  • I updated user-facing documentation and the normative specification when authorized behavior changed.

  • I kept unrelated changes out of this PR.

  • If this is experimental, I prominently marked it and kept it isolated from default behavior, the normative specification, and conformance expectations.

  • I have not presented a working-group study or community preference as an accepted language decision.

@vercel

vercel Bot commented Aug 4, 2026

Copy link
Copy Markdown

@codexbounty260804 is attempting to deploy a commit to the Grida Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Aug 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e563721-06f8-4cef-8eaa-8cb4ecd4a79d

📥 Commits

Reviewing files that changed from the base of the PR and between db42fd3 and 56f11ea.

⛔ Files ignored due to path filters (1)
  • www/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (8)
  • .gitignore
  • README.md
  • llms.txt
  • scripts/generate-llms.mjs
  • sourcey.config.ts
  • vercel.json
  • www/README.md
  • www/package.json

Walkthrough

The change adds a canonical llms.txt index, configures Sourcey to generate it, and integrates validation and publication into the website build. Vercel serves the published file as UTF-8 plain text.

Changes

LLM documentation publishing

Layer / File(s) Summary
Documentation index and Sourcey navigation
llms.txt, sourcey.config.ts		 Adds the curated Spock resource index and grouped documentation navigation.
Canonical file generation
scripts/generate-llms.mjs, README.md		 Adds commands to generate, check, update, and optionally publish llms.txt.
Website build publication and serving
www/package.json, www/README.md, .gitignore, vercel.json		 Runs validation and publication during the website build, ignores the generated copy, documents the workflow, and configures plain-text serving.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WebsiteBuild as website build
  participant GenerateLLMS as generate-llms.mjs
  participant Sourcey
  participant CanonicalFile as root llms.txt
  participant PublicFile as www/public/llms.txt
  WebsiteBuild->>GenerateLLMS: check and publish documentation index
  GenerateLLMS->>Sourcey: generate documentation
  Sourcey-->>GenerateLLMS: generated content
  GenerateLLMS->>CanonicalFile: validate or update canonical content
  GenerateLLMS->>PublicFile: copy canonical content
Loading

Possibly related PRs

  • gridaco/spock#22: This change modifies the same website and deployment files for generated llms.txt publication.

Suggested reviewers: softmarshmallow

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the main change: publishing a Sourcey-generated llms.txt file.
Description check ✅ Passed The description follows the template and includes scope, language-gate details, before/after behavior, verification, and required checklist selections.
Linked Issues check ✅ Passed The changes provide a tracked canonical index, generated website copy, plain-text headers, authoritative links, and build checks against drift for issue #23.
Out of Scope Changes check ✅ Passed All listed changes support issue #23 by implementing, documenting, or configuring the canonical llms.txt generation and publication workflow.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@codexbounty260804

codexbounty260804 commented Aug 4, 2026

Copy link
Copy Markdown
Author

@softmarshmallow This is ready for review: CodeRabbit found no actionable issues, the frozen-lockfile install and 35-page Astro build pass locally, and dist/llms.txt is byte-identical to the canonical root file. The only red check is Vercel asking a Grida team member to authorize this external PR deployment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@softmarshmallow softmarshmallow Awaiting requested review from softmarshmallow softmarshmallow is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

chore: add llms.txt for the repository and spock.sh

1 participant

@codexbounty260804